| # Chained Exception Facility | Documentation Contents

It is common for Java code to catch one exception and throw another:

>     try {
>         ...
>     } catch(YourException e) {
>         throw new MyException();
>     }

Unfortunately, the information contained in the "causative exception" (`YourException` in the example above) is generally lost, which greatly complicates debugging. Recognizing this problem, developers sometimes build ad hoc mechanisms to allow certain "wrapped exceptions" to contain a second exception. An accessor is generally provided to extract the contained exception. Such mechanisms are sometimes known as "exception chaining facilities", as they allow arbitrary chains of exceptions to be constructed when contained exceptions are, themselves, wrapped exceptions.

There are many advantages to unifying all of these facilities. Chief among them are: (1) We guarantee that anyone who wants to record the fact that one exception caused another can do so, regardless of what the exceptions are. (2) By providing a common API to record the fact that one exception caused another, we ease this task, making it more likely that programmers will take the trouble to do it. (3) By providing a common API to access causative exceptions, we greatly increase the likelihood that this information will be made available to those who need it. In fact, the proposed mechanism prints entire "causal chain" as part of the standard stack backtrace, ensuring that preexisting programs will provide this information with no additional effort on the part of their authors.

To address these issues, we have added two new methods to `Throwable`, `getCause()` and `initCause(Throwable)`, and two new constructors, `Throwable(Throwable)` and `Throwable(String, Throwable)`. Other "general purpose" exception classes (like `Exception`, `RunTimeException` and `Error`) have been similarly outfitted with `(Throwable)` and `(String, Throwable`) constructors. However, even exceptions without such constructors will be usable as "wrapped exceptions" via the `initCause` method.

The implementation of `Throwable.printStackTrace` has been modified to display backtraces for the entire causal chain of exceptions. New method `getStackTrace` provides programmatic access to the stack trace information provided by `printStackTrace`.

All of the platform's wrapped exceptions will be retrofitted to support the new facility (in addition to their legacy APIs).

The bugtraq report that corresponds to this change is 4209652.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved. | Java Software